package de.androidbuch.amando.services;

import java.util.List;

import android.app.ProgressDialog;
import android.os.Handler;
import de.androidbuch.amando.common.GpsData;

/**
 * Interface für die öffentlichen Methoden des
 * GeoPositionsService. Der Zugriff auf die Methoden wird
 * über einen Binder realisiert, der Teil der
 * Service-Implementierung ist.
 * 
 * @author Arno Becker, 2010 visionera gmbh
 */
public interface IGeoPositionsService {
  
  /** 
   * Liefert die letzte bekannte eigene Position. 
   * 
   * @return Letzte bekannte eigene Position.
   */
  GpsData getGpsData();

  /**
   * Sendet die zuletzt bekannte eigene Position per SMS an
   * einen Empfänger mit der Mobilnummer 'empfaengerNr'.
   * Falls 'positionAktualisieren' true ist, wird die
   * Position zusätzlich an den Amando-Server geschickt. Der
   * Empfänger der SMS (der Client) ist nun berechtigt, die
   * Positionsänderungen des SMS-Senders nachzuverfolgen.
   * Daher werden Positionsänderungen jeweils an den
   * Amando-Server geschickt. Der
   * @see{GeoPositionsServiceImpl} implementiert einen
   * LocationListener. Dieser schickt bei Ortsveränderungen
   * die aktuelle Position an den Amando-Server, der sie an
   * den Client weiterleitet (allerdings nur, wenn
   * 'positionAktualisieren' true ist).
   * 
   * @param empfaengerMobilnummern
   *          Mobilnummern der Empfänger
   * @param stichwort
   *          ein Stichwort, was an die Empfänger geschickt
   *          wird
   * @param positionAktualisieren
   *          Empfänger darf Positionsänderungen des
   *          SMS-Senders nachverfolgen.
   * @param pd ProgressDialog für die Anzeige während des
   *          Wartens auf eine aktuelle Geoposition.
   */
  void sendeGeoPosition(
      List<String> empfaengerMobilnummern,
      String stichwort, boolean positionAktualisieren,
      ProgressDialog pd);

  /**
   * Übergibt dem Service einen Callback-Handler, um die
   * aktualisierte Position der Clients zu melden. Der
   * Handler wird in der Activity @see{KarteAnzeigen}
   * definiert und dient zum Aktualisieren der Positionen
   * der Clients. Dieser Callback wird direkt an den
   * @see{NetzwerkService} weitergeleitet, da dieser staenig
   * die aktuellen Positionen der Clients in einem Listener
   * registriert.
   * 
   * @param callback
   *          ein Handler-Objekt zur Aktualisierung der
   *          Oberfläche.
   */
  void setAnzeigeCallbackHandler(Handler callback);

}
